﻿using wwl.Domain.Entities.Common;

namespace wwl.Domain.Entities.Rbac
{
  /// <summary>
  /// 权限聚合根（DDD 核心领域实体）
  /// 属于权限模块（Rbac）的核心聚合根，承载系统资源访问控制的最小权限单元定义
  /// 聚合边界：权限定义 + 层级关系 + 资源映射，构成完整的系统权限模型基础
  /// 设计扩展 Camunda 内置权限概念，实现更细粒度和可配置的权限管理体系
  /// </summary>
  public class Permission : BaseEntity
  {
    /// <summary>
    /// 权限编码（领域核心业务标识）
    /// </summary>
    /// <remarks>
    /// 1. 标准化命名：权限编码采用"类型_模块_操作"的命名规范（如 MENU_USER_MANAGEMENT、BUTTON_USER_ADD），
    ///    确保权限标识的清晰性和一致性，便于开发人员和运维人员理解。
    /// 2. 全局唯一性：权限编码在系统内全局唯一，作为权限校验的技术键值，前端和后端的权限控制均依赖此编码。
    /// 3. 稳定性要求：权限编码一旦确定不应修改，因其可能被硬编码在业务逻辑、前端组件或API注解中。
    /// 4. 多租户扩展：通过 TenantId 实现租户内权限编码唯一性，支持不同租户定义相同编码但不同含义的权限。
    /// </remarks>
    public string PermCode { get; set; } = string.Empty;

    /// <summary>
    /// 权限名称（业务展示标识）
    /// </summary>
    /// <remarks>
    /// 1. 用户友好设计：权限名称采用中文描述性文字（如"用户管理菜单"、"新增用户按钮"），
    ///    便于管理员在权限配置界面理解和选择，降低权限管理的学习成本。
    /// 2. 业务语义明确：名称应清晰表达权限对应的业务功能和操作范围，避免歧义和混淆。
    /// 3. 灵活性支持：权限名称可随时调整优化，不影响已有的权限配置和业务逻辑代码。
    /// 4. 多语言预留：128字符长度支持多语言权限名称，为系统国际化提供扩展空间。
    /// </remarks>
    public string PermName { get; set; } = string.Empty;

    /// <summary>
    /// 权限类型（功能分类与层级管理）
    /// </summary>
    /// <remarks>
    /// 1. 三级权限体系：
    ///    - MENU：菜单级权限，控制导航菜单的显示和访问，对应系统的功能模块入口
    ///    - OPERATION：操作级权限，控制API接口和业务功能的执行权限，如数据导出、流程发起
    ///    - BUTTON：按钮级权限，控制界面按钮的显示和操作，实现界面元素的精细化控制
    /// 2. 权限粒度：通过三级分类实现从粗到细的权限控制，满足不同场景的安全管控需求。
    /// 3. 界面适配：前端可根据权限类型采用不同的控制策略，如菜单权限控制路由、按钮权限控制DOM渲染。
    /// 4. 默认操作类型：新创建权限默认为 OPERATION 类型，作为最常见的权限粒度。
    /// </remarks>
    public PermissionType PermType { get; set; } = PermissionType.OPERATION;

    /// <summary>
    /// 父权限标识（权限层级关系构建）
    /// </summary>
    /// <remarks>
    /// 1. 树形结构：通过 ParentId 构建权限的层级关系，支持菜单的多级嵌套和权限的继承关系。
    /// 2. 权限继承：子权限自动继承父权限的某些特性（如可见性、可用性），简化权限配置工作。
    /// 3. 导航支持：层级关系为前端菜单导航和权限树展示提供数据基础，提升用户体验。
    /// 4. 可空设计：根级权限的 ParentId 为 null，标识权限树的顶层节点，简化权限树的遍历逻辑。
    /// </remarks>
    public string? ParentId { get; set; }

    /// <summary>
    /// 资源路径（权限与系统资源映射）
    /// </summary>
    /// <remarks>
    /// 1. 资源绑定：将权限与具体的系统资源建立映射关系，如URL路径、API接口、前端路由等。
    /// 2. 自动鉴权：系统可根据请求的资源路径自动匹配所需权限，实现声明式的访问控制。
    /// 3. 灵活配置：
    ///    - 精确匹配："/api/users" 需要精确权限
    ///    - 通配符匹配："/api/users/*" 支持路径参数场景
    ///    - 正则匹配：复杂资源路径的模式匹配
    /// 4. 性能优化：通过资源路径索引提升权限校验效率，支持高并发场景下的快速权限判断。
    /// </remarks>
    public string? ResourcePath { get; set; }

    /// <summary>
    /// 租户标识（多租户权限隔离）
    /// </summary>
    /// <remarks>
    /// 1. 租户专属权限：每个租户可独立定义自己的权限体系，实现权限模型的完全定制化。
    /// 2. 系统级权限：TenantId 为 null 表示系统级基础权限，为各租户提供权限模板和基准。
    /// 3. 权限复制：支持租户从系统级权限库选择复制，快速建立符合自身业务需求的权限体系。
    /// 4. 数据隔离：通过 TenantId 确保权限数据在租户间的完全隔离，维护多租户系统的安全边界。
    /// </remarks>
    public string? TenantId { get; set; }

    /// <summary>
    /// 父权限导航属性（EF Core 自引用关系）
    /// </summary>
    /// <remarks>
    /// 1. 层级遍历：通过此属性可向上追溯权限的父级节点，支持权限树的完整遍历和路径构建。
    /// 2. 业务验证：在权限配置时验证层级关系的合理性（如避免循环引用、类型一致性等）。
    /// 3. 性能考虑：父权限信息通常缓存使用，避免频繁的数据库查询影响系统性能。
    /// 4. 可空设计：根级权限的 Parent 为 null，简化权限树顶层节点的处理逻辑。
    /// </remarks>
    public virtual Permission? Parent { get; set; }

    /// <summary>
    /// 子权限集合（EF Core 自引用关系）
    /// </summary>
    /// <remarks>
    /// 1. 向下扩展：通过此集合可访问当前权限的所有直接子权限，构建完整的权限子树。
    /// 2. 延迟加载：默认采用延迟加载策略，避免在查询权限列表时自动加载大量子权限数据。
    /// 3. 界面渲染：为前端权限树组件的动态渲染提供数据支持，实现交互式的权限配置界面。
    /// 4. 级联操作：通过数据库外键约束确保子权限删除时的数据一致性，维护权限树的完整性。
    /// </remarks>
    public virtual ICollection<Permission> Children { get; set; } = new List<Permission>();

    /// <summary>
    /// 角色权限关联集合（权限分配关系）
    /// </summary>
    /// <remarks>
    /// 1. 权限分配记录：通过此集合可追溯该权限被分配给了哪些角色，支持权限使用情况分析。
    /// 2. 影响分析：在权限变更时可快速识别受影响的所有角色和用户，支持变更影响评估。
    /// 3. 权限回收：通过操作此集合实现权限的批量分配和回收，提升权限管理效率。
    /// 4. 审计支持：为权限分配历史提供完整的数据记录，满足安全审计和合规性要求。
    /// </remarks>
    public virtual ICollection<RolePermission> RolePermissions { get; set; } = new List<RolePermission>();
  }

  /// <summary>
  /// 权限类型枚举（DDD 领域枚举，定义权限功能分类）
  /// </summary>
  /// <remarks>
  /// 1. 功能维度划分：从用户交互角度将权限划分为三个层次，覆盖从界面导航到具体操作的完整控制链条。
  /// 2. 控制粒度：
  ///    - 菜单权限：最粗粒度，控制功能模块的可见性和可访问性
  ///    - 操作权限：中等粒度，控制业务功能的执行权限
  ///    - 按钮权限：最细粒度，控制界面元素的交互权限
  /// 3. 技术实现：每种权限类型对应不同的前端控制策略和后端校验逻辑，实现技术层面的差异化处理。
  /// 4. 业务扩展：三级分类体系具有良好的扩展性，可适应未来新增的权限控制需求。
  /// </remarks>
  public enum PermissionType
  {
    /// <summary>
    /// 菜单权限：控制导航菜单和功能模块的访问权限，决定用户在系统中能看到和进入哪些功能区域
    /// 典型应用：侧边栏菜单、顶部导航、功能模块入口的控制
    /// </summary>
    MENU,

    /// <summary>
    /// 操作权限：控制业务功能和API接口的执行权限，决定用户能执行哪些业务操作和数据处理
    /// 典型应用：数据导出、流程发起、批量操作、特定功能执行的权限控制
    /// </summary>
    OPERATION,

    /// <summary>
    /// 按钮权限：控制界面按钮和操作元素的交互权限，决定用户在界面上能点击和操作哪些元素
    /// 典型应用：新增按钮、删除按钮、编辑按钮、特殊操作按钮的显示和可用性控制
    /// </summary>
    BUTTON
  }
}